Document rolling and release Kolla image tags - #1062

Documents the two Kolla image tag schemes, how to look up the image parameters
and tags of a specific OSISM version, and fixes the security advisory
remediation snippets that cannot be applied as written in a release-namespace
deployment.

Reported in osism/issues#1430.

Problem

The advisories tell operators to pin a rolling tag in
environments/kolla/images.yml:

neutron_server_tag: "2025.1"

A deployment that follows the OSISM 10 release
notes
and sets docker_namespace: kolla/release/2025.1 resolves this to
registry.osism.tech/kolla/release/2025.1/neutron-server:2025.1, which does not
exist. The pull fails with unknown: artifact ... not found.

Both settings are individually correct and documented. The combination is not,
and nothing documented that. Nothing documented either where the tags that can
be set come from, or which image parameters exist in the OSISM version actually
deployed — the guide only linked 002-images-kolla.yml at main.

What was verified, and how

Everything factual below was checked against the registry or the source. Listing
it explicitly so nothing here has to be taken on trust.

Method. All registry facts come from skopeo — skopeo list-tags,
skopeo inspect and skopeo copy against docker://registry.osism.tech/....
The Harbor token endpoint and /v2/<repo>/tags/list were not queried
directly with a bearer token. skopeo needs no credentials for these
repositories, is the tool the OSISM stack itself uses (osism sync versions),
and is therefore also what the added documentation shows as the example command,
so every listing below is reproducible with a single command.

1. The two namespaces have disjoint tag sets. skopeo list-tags, re-run on
2026-08-21:

2. Why they are disjoint. src/tag-images-with-the-version.py:221 in
container-images-kolla moves release builds into
/kolla/release/<OPENSTACK_VERSION>/ using only the computed
<version>.<build date> tag. The rolling tag is never rewritten into that
namespace, so the split is by construction, not a publishing gap. Introduced in
osism/container-images-kolla#672.

3. The rolling tag carries the OSSA-2026-032 fix. skopeo inspect docker://registry.osism.tech/kolla/neutron-server:2025.1: created 2026-08-21T01:33:57Z, org.opencontainers.image.version = 26.0.6,
de.osism.version = latest. The advisory names 26.0.6 as the fixed Epoxy
version.

4. The release namespace now carries it too, from OSISM 10.2.0 on.
10.2.0/base.yml in osism/release pinned Kolla 0.20260813.0 when the release
was prepared on 2026-08-13 and was bumped to 0.20260814.0 one day later by
osism/release#2665. Extracting
/sbom.yml from osism/kolla-ansible:0.20260814.0 (skopeo copy into a dir:,
then the layer holding it) gives versions.neutron: 26.0.6.20260814, and
skopeo inspect on
kolla/release/2025.1/neutron-server:26.0.6.20260814 reports
org.opencontainers.image.version = 26.0.6. OSISM 10.1.0 pins Kolla
0.20260328.0, from before the advisory, so it is unaffected by this and still
needs the override.

The build and tag names verified here are deliberately not repeated in the
advisory text. Neutron 26.0.6 is not released upstream — PyPI's newest Epoxy
release is 26.0.5 — so naming it as the fixed version would contradict the
affected versions table further up in the same file, which lists 26.0.6 as
proposed and not yet merged. The advisory therefore only states that OSISM
10.2.0 ships the patched images.

Worth flagging separately: the build 10.2.0 originally pinned,
0.20260813.0, contains no neutron images at all — its SBOM lists 120 images
and has no neutron key, where the complete builds list 133 and 60 versions.
With that SBOM, kolla_neutron_version falls back to openstack_version, so
neutron would have resolved to kolla/release/2025.1/neutron-server:2025.1,
a tag that does not exist. osism/release#2665 fixed that as well.

5. Which images each recommended tag covers. Read from
osism/defaults/all/002-images-kolla.yml at main: keystone_tag drives four
images (keystone, keystone-fernet, keystone-ssh, httpd), nova_tag
drives ten, neutron_server_tag and nova_api_tag one each.
nova_libvirt_tag derives from kolla_nova_libvirt_version, not nova_tag;
that is why nova_libvirt is absent from the OSSA-2026-002 block, which the
snippet no longer spells out.

osism/defaults at main also defines neutron_rpc_server_image,
neutron_periodic_worker_image and neutron_ovn_maintenance_worker_image,
which default to neutron_server_image. Those parameters were introduced with
kolla-ansible 2025.2 and do not exist in stable/2025.1 (checked in a clone of
openstack/kolla-ansible), so they cannot apply to any OSISM release and are
not mentioned in the docs.

6. The version lookup chain in the new section. 10.2.0/base.yml pins
defaults_version: v0.20260712.0; that tag exists in osism/defaults and holds
both all/002-images-kolla.yml and all/002-images-ceph.yml, so both links
resolve.

7. Build and lint pass. yarn build succeeds with onBrokenLinks: 'throw';
the new anchor id="rolling-tags-and-release-tags" is generated and the inbound
links resolve. MegaLinter (documentation flavor: markdownlint,
markdown-table-formatter, codespell) reports no findings. The
unsupported file type SVG warnings in the build output are pre-existing and
unrelated.

Changes

• configuration-guide/openstack/index.md — new Rolling tags and release tags section covering both schemes and the *_image override, which is the
  explanation of tag semantics asked for in the issue, plus a new Image parameters and tags of a specific OSISM version section: osism/release →
  10.2.0/base.yml → defaults_version: v0.20260712.0 →
  002-images-kolla.yml / 002-images-ceph.yml at that tag, with skopeo list-tags examples for the tags of both namespaces.
• release-notes/osism-10.md — states the tag scheme of the new namespace
  next to the docker_namespace change that introduced it, and warns that it
  holds no rolling tags.
• OSSA-2026-001, -002, -005, -015, -022, -032 — each rolling-tag snippet
  gains the companion *_image override.
• OSSA-2026-032 — additionally names OSISM 10.2.0 as the first release that
  ships the patched images, so release-namespace deployments can see that
  upgrading is now enough and the override is no longer required there.
• OSSA-2026-015, -022, -032, -034 — the tag examples no longer offer
  "2025.2". OSISM ships only the SLURP releases, 2024.1 in OSISM 8, 2024.2 in
  OSISM 9 and 2025.1 in OSISM 10, so it is never the OpenStack release of a
  deployment following these instructions. This is the only change to
  OSSA-2026-034, which is otherwise untouched by this PR, and it is a separate
  commit because it corrects lines that predate this branch.

The advisory snippets list every image the recommended tag covers, since a
partial override leaves the rest of the service pointing at a tag that does not
exist. That is why the nova_tag block in OSSA-2026-002 is ten lines.

Review feedback

Changes made after @janhorstmann's review, all folded into the commits that
introduced the affected lines except the 2025.2 trim:

• The "only the images actually used in the deployment need to be set" note and
  the nova_libvirt_tag aside are gone from OSSA-2026-002. Overriding an unused
  image has no downside, and the block already lists everything.
• The neutron_rpc_server_image note is gone from OSSA-2026-032 and from the
  configuration guide, for the 2025.2 reason given in verification item 5. The
  guide now states the general mechanism instead: each image has its own
  *_image, while the *_tag values derive from one service tag.
• The OSSA-2026-032 release paragraph was shortened to the statement that
  10.2.0 ships the patched images, dropping the Kolla build and image tag, see
  verification item 4.

Not taken: the suggestion to replace the *_image plus *_tag pairs with a
single list of *_image_full entries. It would be more copy-pastable, but it
changes the override style the advisories and the guide use throughout, and
*_image_full is a kolla-ansible role default rather than a parameter
osism/defaults exposes — keystone_httpd_image_full, for one, does not exist
anywhere. Worth discussing separately from this PR.

Judgment calls, for review

These are decisions rather than verified facts, so they are the parts most worth
a second opinion:

• Placement in OSSA-2026-015 — its snippet is already followed by a
  trust-policy warning, so this one was added after it rather than between the
  snippet and that warning.
• Remediation scope left untouched — in OSSA-2026-002 the qemu-img path is
  reached in nova-compute, so the advisory's service-wide nova_tag is broader
  than strictly needed. Narrowing a published advisory's remediation seemed out
  of scope for a docs fix, so the scope was kept and made to work.
• Wording of the kolla namespace as "rolling" — taken from the advisories'
  own existing phrasing ("Using rolling tags, ...") rather than newly coined.
• The overrides were kept in OSSA-2026-032 rather than replaced by "upgrade
  to 10.2.0", since they remain the only route for 10.1.0 and earlier.

Not addressed here

The neutron-less Kolla build 0.20260813.0 and the fact that the 10.2.0
release entry pointed at it for a day are noted above but not acted on; whether
that needs anything beyond osism/release#2665 is a maintainer call.

Separately, osism sync versions --release <version> looks broken: its defaults
build the SBOM reference as
registry.osism.cloud/kolla/release/sbom:<kolla version>, a repository whose
newest tag is 0.20251130.0, while the current SBOM images live at
registry.osism.tech/kolla/release/<openstack_version>/sbom:<kolla version>.
That belongs in python-osism, not here, and is why the new documentation shows
skopeo list-tags rather than that command.

Open questions from the issue

The reporter asked three questions that this PR answers in the docs, but which
are worth confirming as correct:

1. docker_namespace: kolla/release/2025.1 is correct and should stay.
2. It does not need overriding wholesale, only per-image alongside a rolling tag,
   and from OSISM 10.2.0 on not even that for OSSA-2026-032.
3. Unpinned images are unaffected, because their versions come from the
   versions.yml rendered in the osism/kolla-ansible image from its baked-in
   SBOM.